% ----------------------------------------------------------------------------
% File: docVirtualVisit.tex
% Usage:        Latex2e
% ----------------------------------------------------------------------------
\documentclass[12pt, a4paper]{article}
\usepackage[french]{babel}
\usepackage{epsfig}
\usepackage{fancyhdr}
\usepackage[utf8]{inputenc}
\usepackage{graphicx}
\usepackage[colorlinks=true,linkcolor=black]{hyperref}

% --- Commandes --------------------------------------------------------------
%\newcommand{\AffichePs}[2]{\centerline{\psfig{figure=#1,#2}}}

\renewcommand\contentsname{Table des mati\`eres}

\def\ladate{Janvier 2009}

\def\mot-cle#1{
{\noindent {\bf Mots-cl\'es} : #1\vspace{-.5em}\vspace{0pt}}
\def\mot-cle{\par}
}

\def\biblio#1{\subsection{R\'ef\'erences}\list
 {[\arabic{enumi}]}{\settowidth\labelwidth{[#1]}\leftmargin\labelwidth
 \advance\leftmargin\labelsep
 \usecounter{enumi}}
 \def\newblock{\hskip .11em plus .33em minus .07em}
 \sloppy\clubpenalty4000\widowpenalty4000
 \sfcode`\.=1000\relax}
\let\endbiblio=\endlist


% --- Identification du document ---------------------------------------------
\def\letitre{\bf\sc VirtualVisit \\
 projet Syst\`emes Distribu\'es }
\def\entete{\bf\sc VirtualVisit : Projet de S.D. }
\def\lesoustitre{\bf\sc Visite Virtuelle}
\def\lesujet{\bf\sc Documentation de r\'ealisation}
\def\leclient{ENIB}
\def\lauteur{Nicolas PIEGAY et Julien MANANKIANDRIANANA}
\def\leverif{Y}
\def\lechef{N. PIEGAY}
\def\laversion{1}
\def\enib{{\sc Ecole Nationale d'Ing\'enieurs de Brest}}

% --- Mise en page ------------------------------------------------------------
\setlength{\textheight}{23.6cm}
\setlength{\textwidth}{16cm}
\setlength{\parindent}{0cm}
\voffset=-1cm
\hoffset=-1cm

\pagestyle{fancy}
\lhead{\scriptsize{\entete}}
\rhead{\scriptsize{SD}}
\lfoot{\scriptsize{\leclient}}
\cfoot{\scriptsize{\thepage}}%/\pageref{fin}}}
\rfoot{\scriptsize{Version \laversion - \ladate}}

\begin{document}
% ----------------------------------------------------------------------------
\begin{titlepage}
% ---------------
\begin{center}
{\LARGE\sc \'Ecole Nationale d'Ing\'enieurs de Brest}
\vspace{.8cm}

\mbox{\LARGE\sc Projet Syst\`emes Distribu\'es}
\vspace{2cm}
\includegraphics[width=8cm]{./img/ban01.jpg}
\vspace{1cm}
\begin{bfseries}

\vspace{1cm}
\begin{Huge}
\letitre
\end{Huge}

\vspace{1cm}
\begin{Large}
%\lesoustitre\\

\vspace{1cm}
\lesujet
\vspace{1cm}

\end{Large}
\lauteur
\null\vfill
%\vspace{6cm}
\begin{large}
\mbox{\leclient}\\
\end{large}

\vspace{1cm}
2008

\end{bfseries}
\end{center}

\end{titlepage}

%\null\vfill
\newpage
% -------------------



% --- Table des matieres ---
\tableofcontents
%\newpage
% --- Table des figures ---
\listoffigures
\newpage

%------------------------------------------
\section{Introduction}

	\subsection{Objectifs du document}
		\paragraph*{}
		Ce document a pour objectif de d\'ecrire quelques particularit\'es et d\'etails d'impl\'ementation du projet. Il n'est en aucun cas une sp\'ecification technique exhaustive; mais simplement une aide \`a la compr\'ehension.

	\subsection{D\'efinitions des besoins}
		
		\paragraph*{}
		\textit{On souhaite d\'evelopper une application de type r\'ealit\'e virtuelle distribu\'ee consistant en la visite d'un monde virtuel. Cette visite met en oeuvre plusieurs visiteurs, chacun contr\^ol\'e par un ordinateur. Le r\'esultat de la visite est une vue (1) du site (2) des autres visiteurs.}
		\paragraph*{}
		\textit{De plus on suppose qu'un visiteur, appel\'e le guide (pas toujours le m\^eme et pendant une dur\'ee de temps born\'ee \`a priori) peut entra\^iner \`a sa suite les autres visiteurs (ces autres visiteurs ne s'\'eloignent pas du guide).}
		\paragraph*{}
		\textit{Les fonctionnalit\'es du syst\`eme \`a d\'evelopper sont les suivantes :
			\begin{itemize}
				\item Connexion (d\'econnexion) \`a la visite;
				%\item Diffusion de l'\'etat de chaque visiteur aux autres en utilisant un m\'ecanisme de dead-reckoning;
				\item Restriction des interactions en utilisant les m\'ecanismes d'attention;
				\item Prise du r\^ole du guide en exclusion mutuelle.
			\end{itemize}
		}%end textit
\clearpage
\section{R\'ealisation}

	\subsection{Arborescence du projet}
	Notre projet est constitu\'e de trois parties :
		\begin{itemize}
		 \item Le serveur charg\'e d'accepter les connexions entrantes et de traiter les requ\^etes;
		 \item Les clients qui se connectent au serveur et envoient leurs requ\^etes;
		 \item Une partie commune aux deux parties pr\'ec\'edentes (format des messages \`a envoyer, informations sur les clients, etc).
		\end{itemize}
		\begin{figure}[!h] %on ouvre l'environnement figure
			\center
			\includegraphics[scale=0.85]{./img/appTree.png} %ou image.png, .jpg etc.
			\caption{\textit{Arborescence du projet}}
			\label{appTree} %l'\'etiquette pour faire r\'ef\'erence \'e cette image
		\end{figure} %on ferme l'environnement figure		
		%TODO	

	\subsection{R\'eseau}

		\paragraph*{}
		Nous avons choisie la topologie \'etoile : tous les clients se connectent \`a un unique serveur qui indique \`a chaque client les informations 
		sur les autres.
		
		\subsubsection{C\^ot\'e serveur}
		\paragraph*{} L'application est compos\'ee d'un serveur global \`a l'\'ecoute des connexions entrantes des clients et qui, \`a chaque 
		nouvelle connexion, instancie un {\tt{ServerHandler}} qui traitera toutes les requ\^etes de ce client.
		Pour permettre aux clients de conna\^itre le nombre de clients connect\'es sur un serveur et leurs positions, nous 
		avons cr\'e\'e une classe {\tt{VistorsGroup}} qui contient une liste de tous les clients connect\'es. Le diagramme UML ci-dessous illustre l'architecture
		mise en place côté serveur.

		\begin{figure}[!h] %on ouvre l'environnement figure
			\center
			\includegraphics[width=15cm]{./img/serverUML.png} %ou image.png, .jpg etc.
			\caption{\textit{Diagramme UML - Server}}
			\label{serverUML} %l'\'etiquette pour faire r\'ef\'erence \'e cette image
		\end{figure} %on ferme l'environnement figure
		\clearpage

		\subsubsection{C\^ot\'e client}
		\paragraph*{} Il \'etait tr\`es important que l'architecture soit bien structur\'ee c\^ot\'e client. Nous avons donc bien s\'epar\'e les 
		diff\'erentes parties de mani\`ere \`a obtenir :
		\begin{itemize}
		 \item Une partie r\'eseau qui informe les autres clients par le biais du serveur les changements locaux et qui r\'ecup\`ere les informations 
		changements sur les changements distants;
		 \item Une partie ihm/vue qui permet \`a l'utilisateur d'interagir avec l'application;
		 \item Une partie de contr\^ole des \'ev\`enements qui fait le lien entre les 2 parties pr\'ec\'edentes et permet d'avoir une bonne coh\'erence 
		globale.
		\end{itemize}
		
	\subsubsection{Communication par messages}

		\paragraph{Modélisation statique}
		Les ordinateurs des différents visiteurs communiquent entre eux par le réseau via des messages. Voici la structure des messages dans notre application :


		\begin{figure}[h] %on ouvre l'environnement figure
			\center
			\includegraphics[width=14cm]{./img/messagesUML.png} %ou image.png, .jpg etc.
			\caption{\textit{Diagramme UML - Messages}}
			\label{messagesUML} %l'\'etiquette pour faire r\'ef\'erence \'e cette image
		\end{figure} %on ferme l'environnement figure

		\paragraph*{}La communication par message nous permet d'ajouter de nouvelles fonctionnalités simplement en créant une nouvelle classe qui hérite d'{\tt{AbstractVisitorBasedMessage}} et 
		en définissant comment les messages seront parsés une fois reçus.


		Voici un exemple plus détaillé : 
		\clearpage
		\begin{figure}[h] %on ouvre l'environnement figure
			\center
			\includegraphics[width=14cm]{./img/messagesExampleUML.png} %ou image.png, .jpg etc.
			\caption{\textit{Diagramme UML - Exemple plus détaillé}}
			\label{messagesExampleUML} %l'\'etiquette pour faire r\'ef\'erence \'e cette image
		\end{figure} %on ferme l'environnement figure

		\paragraph*{}Une méthode importante est la méthode {\tt{messageToString}} qui permet de sérialiser l'objet message. Tous les messages sont sérialisés lorsqu'on les envoie à travers le 
		réseau. \`A la réception, on instancie des messages de même type en parsant le début de la chaîne de caractère reçue, le reste de la chaîne est alors parsé dans le constructeur du 
		message en question qui extrait les informations envoyées.




		\paragraph{Modélisation dynamique}
			La dynamique des messages est inspirée de celle proposée dans le code du {\tt{NetTour3D}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	\subsection {Architecture de l'application}
		
		\subsubsection{Programmation \'evenementielle}
		\paragraph*{} Pour que l'application locale ainsi que les applications distantes puissent r\'eagir aux changements locaux ou distants nous avons
		d\'ecid\'e d'utiliser les \'ev\`enements. Ceci nous a permis d'obtenir une bonne coh\'erence au niveau des positions respectives 
		de chacun des clients mais aussi une possibilit\'e d'\'evolution de l'application plus rapide (passer \`a une vue en 3D, etc). Ainsi quand le
		{\tt{Thread}} d'\'ecoute du r\'eseau du client re\c coit une mise \`a jour d'un client distant, celui-ci g\'en\`ere un \'ev\`enement contenant 
		toutes les informations sur la mise \`a jour pour que la partie visualisation r\'eagisse en cons\'equence.\\

		Pour créer une nouvelle vue à l'écoute des évènements émis par le réseau, il suffit simplement d'implémenter l'interface {\tt{VisitorListener}} et
		de définir les fonctions relatives à l'arrivée d'un nouveau client, son déplacement, son départ, ou au fait qu'il soit ou ne soit plus guide.

 		\begin{verbatim}
 
 			public interface VisitorListener {
         public void visitorCreated(VisitorCreatedEvent evt);
         public void visitorUpdated(VisitorUpdatedEvent evt);
         public void visitorDeleted(VisitorDeletedEvent evt);
         public void visitorGuide(VisitorGuideEvent evt);
       }
 		\end{verbatim}

		\subsubsection{Couche graphique}
		\begin{figure}[h] %on ouvre l'environnement figure
			\center
			\includegraphics[width=14cm]{./img/graphic2D.png} %ou image.png, .jpg etc.
			\caption{\textit{Architecture de la couche graphique}}
			\label{couche2D} %l'\'etiquette pour faire r\'ef\'erence \'e cette image
		\end{figure} %on ferme l'environnement figure
		%\clearpage
		\paragraph*{} Chaque client connect\'e \`a notre serveur est repr\'esent\'e en 2D par un {\tt{VisitorSprite}} qui poss\`ede une r\'ef\'erence 
		sur le {\tt{Visitor}} qu'il repr\'esente. Toutes ces repr\'esentations sont affich\'ees dans un conteneur {\tt{VisitorLayer}} qui vient ajouter,
		retirer ou d\'eplacer les repr\'esentations lorsque les clients se connectent, se d\'econnectent ou se d\'eplacent.
		Les interactions de l'utilisateur sont g\'er\'ees gr\^ace \`a la classe {\tt{VisitorLayerController}}. L'utilisateur du programme utilise les touches z, q, d du clavier pour manipuler son avatar local.
		
		\subsubsection{Utilitaires divers}
			
			\paragraph*{Propri\'et\'es}
			Afin de pouvoir modifier les propri\'et\'es de l'application sans avoir \`a recompiler le code, nous avons introduit un m\'ecanisme de propri\'et\'es. Les propri\'et\'es sont stock\'ees dans une feuille de propri\'et\'es sous la forme cl\'e/valeur puis acc\'ed\'ees depuis l'application par la m\'ethode statique {\tt{getProperty}} de la classe {\tt{Config}}.\\
		Voici un extrait du fichier de configuration {\tt{appconfig.properties}} présent à la racine du projet : 
			\begin{verbatim}
			# Server
			server.port = 5555
			server.timetobeguideinmillisec = 1000
			# Client
			client.hostip = 127.0.0.1
			client.hostport = 5555
			\end{verbatim}

			\paragraph*{Log}
			Pour pouvoir avoir un syst\`eme de log param\'etrable au sein de l'application, nous avons choisi {\tt{SLF4J}} qui est une interface de Logging permettant de venir plugger par l'ajout d'un simple fichier jar, une impl\'ementation de Logging telle que {\tt{Log4J}} ou {\tt{Logback}} par exemple. C'est la solution {\tt{logback}} qui a été retenue.\\


	\subsection { Partie distribu\'ee }

		\subsubsection{Notion de guide}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
		\paragraph*{} Dans notre application, chacun des clients \'evoluant dans le monde virtuel peut faire la requ\^ete pour devenir guide. Un guide
		est un client dont le r\^ole est un peu particulier dans le sens ou les autres utilisateurs ne peuvent pas trop s'\'eloigner de lui.
		La figure ci-dessus illustre l'\'ex\'ecution de l'application avec un des clients comme guide (en vert).
		\begin{figure}[!h] %on ouvre l'environnement figure
			\center
			\includegraphics[scale=0.85]{./img/guide.png} %ou image.png, .jpg etc.
			\caption{\textit{Simulation avec guide}}
			\label{guide} %l'\'etiquette pour faire r\'ef\'erence \'e cette image
		\end{figure} %on ferme l'environnement figure
		\paragraph*{} La notion de guide est g\'er\'ee par la classe {\tt{GuideManager}} qui est associ\'ee \`a chaque instance de la classe 
		{\tt{VisitorsGroup}} dont nous avons parl\'e pr\'ec\'edemment. C'est cette classe qui veille \`a ce qu'il n'y est pas plusieurs guide \`a la 
		fois. Pour ce faire, toutes les requ\^etes de guide sont trait\'ees par cette classe qui v\'erifie si un guide est d\'ej\`a d\'efini et si son
		temps en tant que guide s'est \'ecoul\'e (ce temps est réglable via la feuille de propriétés située à la racine du projet). C'est \`a elle qu'il incombe d'informer l'ensemble des clients connect\'es quand le guide change.
		



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Execution du programme}
	\paragraph*{}
		Voici les étapes permettant de lancer l'application :

		\begin{enumerate}
			\item Paramétrer au besoin le fichier de propriétés à la racine du projet (notamment les paramètres de connexion);		
			\item Lancer le serveur a l'aide du script runserver.sh;
			\item Lancer les clients à l'aide du script runclient.sh;
			\item Utiliser le programme.
		\end{enumerate}

	\paragraph*{Scénario d'éxecution}
	Voici un exemple de scénario de test :
	\begin{enumerate}
		\item Paramétrer {\tt{server.port}} dans {\tt{appConfig.properties}}.
		\item Régler également les paramètres pour les clients.
		\item Ouvrir trois terminaux.
		\item Lancer le serveur dans un terminal avec {\tt{runserver.sh}}.
		\item Lancer un client dans un autre terminal avec {\tt{runclient.sh}}.
		\item Lancer le deuxième client dans le dernier terminal avec {\tt{runclient.sh}}.
		\item Vous devriez avoir quatres fenêtres qui sont apparues (2 par client).
		\item Mettre le focus sur une des vues 2D et bouger le visiteur local avec les touches du clavier 'z' 'q' et 'd'.
		\item Vous devriez alors le voir bouger dans toutes les vues 2D.
		\item Cliquer sur le bouton pour devenir guide dans une des ihm.
		\item Un visiteur est alors guide.
		\item Si les autres visiteurs entrent dans son périmètre d'action, il ne pourront plus en ressortir.
	\end{enumerate}

\section{Remarques - Mises en garde}
	\paragraph*{Unicité des noms de clients}
		Cette version n'est pas protégée contre les doublons de noms d'utilisateurs. Ce serait une amélioration a apporter pour une prochaine version.
		Assurez donc vous bien que les noms générés aléatoirement ne sont pas identiques avant d'effectuer des opérations.

	\paragraph*{}
	Par manque de temps, le {\tt{Dead-reckoning}} n'a pas été traité.

	\paragraph*{}
		Nous nous sommes cependant efforcés de garder une logique claire, de séparer autant que possible les composants logiques ainsi que d'intégrer des outils (comme le log et les 
		propriétés) permettant de faciliter le développement, la maintenance et l'utilisation.

	\paragraph*{}
	Merci de reporter tout problème à npiegay@enib.fr ou jmananki@enib.fr.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 


\label{fin}
% ------------------------------------------------------------------------------
\end{document}
